home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / ICON / ICONV8 / Docs / Tr90-2 < prev    next >
Text File  |  1990-07-19  |  57KB  |  2,113 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                Installation Guide for Version 8 of
  15.                       Icon on UNIX Systems*
  16.  
  17.  
  18.                         Ralph E. Griswold
  19.  
  20.  
  21.  
  22.  
  23.                             TR 90-2f
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.           January 1, 1990; last modified April 3, 1990
  50.  
  51.  
  52.                  Department of Computer Science
  53.  
  54.                     The University of Arizona
  55.  
  56.                       Tucson, Arizona 85721
  57.  
  58.  
  59.  
  60.  
  61. *This work was supported by the National Science Foundation under
  62. Grant CCR-8901573.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.                Installation Guide for Version 8 of
  77.                       Icon on UNIX Systems
  78.  
  79.  
  80.  
  81.  
  82. 1.__Introduction
  83.  
  84.    Version 8 is the current version  of Icon and replaces Version
  85. 7.5.  Version 8 contains several new features and improvements to
  86. the implementation [1]. Most changes to the language are upward
  87. compatible with earlier versions of Icon.  Icon programs may need
  88. to be recompiled, however, when Version 8 is installed.
  89.  
  90.    This report provides the information necessary to install Ver-
  91. sion 8 of Icon on computers running UNIX. For other operating
  92. systems, see [2].  The installation process for Version 8 is very
  93. similar to that for Version 7.5.
  94.  
  95.    The implementation of Icon is designed so that it can be
  96. installed, largely automatically, on a variety of computers run-
  97. ning different versions of UNIX. This is accomplished by provid-
  98. ing configuration information that tailors the installation to
  99. specific computers and versions of UNIX.  Appendix A contains a
  100. list of supported configurations.
  101.  
  102.    These systems are referred to as ``supported'' in this report.
  103. Some of these originated under earlier versions of Icon, and not
  104. all of these have been tested yet under Version 8.  The systems
  105. marked with an asterisk have been tested under Version 7.5 or 8
  106. and are referred to as ``tested'' in this report. Not all of
  107. these have been tested under Version 8, so minor difficulties are
  108. possible.
  109.  
  110.    If your system is a tested one, the installation of Version 8
  111. of Icon should be as simple as issuing a few make commands.  If
  112. your system is supported but untested, you may be able to install
  113. it without modification, but if problems show up, you may have to
  114. make minor modifications in configuration files.  If your system
  115. is not in this list, it may have been added since this report was
  116. written. See Section 2.1 for information on how to get a current
  117. list of configurations and their statuses. In some cases, there
  118. may be partial configuration information. If the configuration
  119. information for your system is partial or lacking altogether, you
  120. still may be able to install Version 8 of Icon by providing the
  121. information yourself, using other configurations are a guide. See
  122. Section 3.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                              - 1 -
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. 2.__The_Installation_Process
  140.  
  141.    There are only a few steps needed to install Icon proper. In
  142. addition to Icon itself, there are a number of optional com-
  143. ponents that can be installed: a program library [3], a personal-
  144. ized interpreter system [4], a variant translator system [5], and
  145. a memory-monitoring system [6].  You may want to review the
  146. technical reports describing these optional components before
  147. beginning the installation. In any event, the installation of
  148. optional components can be done separately after Icon itself is
  149. installed.
  150.  
  151.    There are Makefile entries for most steps. Those steps are
  152. marked by asterisks. Steps that are optional are enclosed in
  153. brackets.
  154.  
  155. Icon_Proper
  156.  
  157.      1.     Decide where to unload Icon.
  158.  
  159.      2.     Unload the Icon hierarchy at the selected place.
  160.  
  161.      [3.*]  Check the status of the configuration for your sys-
  162.             tem.
  163.  
  164.      4.     Set up paths.
  165.  
  166.      5.*    Configure the source code for your system.
  167.  
  168.      6.*    Check the size of a header file; if it is not large
  169.             enough, adjust a configuration parameter and start
  170.             again at Step 5.
  171.  
  172.      7.*    Compile Icon.
  173.  
  174.      8.*    Install the compiled files.
  175.  
  176.      9.*    Run some simple tests to be sure Icon is working.
  177.  
  178.      [10.*] Run a test suite.
  179.  
  180. The_Icon_Program_Library
  181.  
  182.      [1.*]  Compile the Icon program library
  183.  
  184.      [2.*]  Test the Icon program library
  185.  
  186.      [3.]   Copy the Icon program library to a public place.
  187.  
  188. The_Icon_Personalized_Interpreter
  189.  
  190.      [1.*]  Build the Icon personalized interpreter system.
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                              - 2 -
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.      [2.*]  Test the Icon personalized interpreter system.
  206.  
  207.      [3.]   Copy the personalized interpreter system to a public
  208.             place.
  209.  
  210. The_Icon_Variant_Translator_System
  211.  
  212.      [1.*]  Test the Icon variant translator system.
  213.  
  214.      [2.]   Copy the variant translator system to a public place.
  215.  
  216. The_Icon_Memory-Monitoring_System
  217.  
  218.      [1.*]  Build the monitoring programs.
  219.  
  220.      [2.*]  Test the monitoring programs.
  221.  
  222. Benchmarking
  223.  
  224.      [1.*]  Timing test programs.
  225.  
  226. Finishing_Up
  227.  
  228.      [1.]   Install documentation for the various components of
  229.             Icon.
  230.  
  231.      [2.*]  Remove files that are no longer needed.
  232.  
  233. 2.1__Installing_Icon_Proper
  234.  
  235. Step_1:_Deciding_Where_to_Unload_Icon
  236.  
  237.    The default location for all files, including executable
  238. binaries, is in the directory /usr/icon/v8.  You can unload the
  239. distribution in another area, or move the files later, but the
  240. installation is easiest if the default location is used.  If you
  241. decide not to put Icon at the default location, read the discus-
  242. sion at Step 4 before going on.
  243.  
  244.    In the balance of this report, relative paths and the location
  245. of files are given with respect to the location into which the
  246. Icon hierarchy is unloaded. For example, a reference to make is
  247. with respect to the Makefile at the top level of this hierarchy
  248. (/usr/icon/v8/Makefile for the default location).  Similarly,
  249. config/unix corresponds to /usr/icon/v8/config/unix for the
  250. default location.
  251.  
  252. Step_2:_Unloading_the_Files
  253.  
  254.    The distribution consists of a hierarchy, which is rooted in
  255. ``.''.  Icon is distributed in a variety of formats.  It requires
  256. about 4.5MB of disk space when unloaded.
  257.  
  258.    The usual distribution medium is magnetic tape, although it is
  259.  
  260.  
  261.  
  262.                              - 3 -
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. also available on cartridges and diskettes.
  272.  
  273. Tapes: The Icon system is provided on tape in tar or cpio format,
  274. recorded at 1600 or 6250 bpi.  The format and recording density
  275. are marked on the label on the tape.
  276.  
  277.    To unload the tape, cd to the directory that is to hold the
  278. Icon hierarchy (the default location is /usr/icon/v8 as mentioned
  279. above) and mount the tape.  The precise tar or cpio command to
  280. unload the distribution tape depends on your local environment.
  281. On a VAX running 4.nbsd, use the following command for a 1600 bpi
  282. tar distribution tape:
  283.  
  284.         tar x
  285.  
  286. Similarly, on a VAX running System V with a 6250 bpi cpio tape,
  287. use:
  288.  
  289.         cpio -icdB </dev/rmt/0h
  290.  
  291. The c (compatibility) and B (blocked) options are essential.
  292.  
  293. Cartridges: Data cartridges are functionally equivalent to mag-
  294. netic tapes, but they are not blocked. For example, on a Sun
  295. Workstation with a cpio cartridge, cd to the directory that is to
  296. hold the Icon hierarchy and use
  297.  
  298.         cpio -icd </dev/rst0
  299.  
  300.  
  301. Diskettes: Diskettes contain cpio files on diskettes in MS-DOS
  302. format.  Copy the *.cpi files on the diskettes to the directory
  303. that is to hold the Icon hierarchy and use a script such as the
  304. following:
  305.  
  306.         for i in *.cpi
  307.         do
  308.            cpio -icd <$i.cpi
  309.         done
  310.  
  311.  
  312.    After the distribution files are unloaded, the resulting
  313. hierarchy should look like this:
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                              - 4 -
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.                          |-bin-------                executable binaries
  338.                          |
  339.                          |-bench-----                benchmarks
  340.                          |
  341.                          |-calling-------            Icon-C interfaces
  342.                          |
  343.                          |-config----|-unix------    UNIX configurations
  344.              |-v8--------|
  345.                          |-docs                      documents
  346.                          |
  347.                          |-ipl-------                program library
  348.                          |
  349.                          |-memmon----                memory monitor
  350.                          |
  351.                          |-pi--------                personalized interpreters
  352.                          |
  353.                          |-samples---                sample programs
  354.                          |
  355.                          |           |-common----    common source
  356.                          |           |-h---------    header files
  357.                          |-src-------|-icont-----    icont source
  358.                          |           |-iconx-----    iconx source
  359.                          |           |-memmon----    memory-monitoring source
  360.                          |
  361.                          |-tests-----                test suite
  362.                          |
  363.                          |-vt--------                variant translator
  364.  
  365.  
  366. In some cases there are subdirectories not shown above.
  367.  
  368. Step_3:_Checking_the_Status_of_the_Configuration_for_Your_System
  369.  
  370.    You may wish to check the status of the configuration for your
  371. system.  This can be done by
  372.  
  373.         make Status name=name
  374.  
  375. where name is one of those given in the table in Appendix A.  For
  376. example,
  377.  
  378.         make Status name=vax_bsd
  379.  
  380. lists the status of the configuration for a VAX running BSD UNIX.
  381.  
  382.    In many cases, the status information was provided by the per-
  383. son who first installed Icon on the system in question. The
  384. information may be old and possibly inaccurate; use it as a
  385. guideline only.
  386.  
  387.    There are some supported systems for which not all features of
  388. Icon are implemented. If the status information shows this for
  389. your system, proceed with the installation, but you may wish to
  390. implement the missing features later. For this, see Section 3
  391.  
  392.  
  393.  
  394.                              - 5 -
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403. after completing the basic installation.
  404.  
  405. Step_4:_Setting_Up_Paths
  406.  
  407.    If you unloaded Version 8 of Icon at the default location and
  408. plan to leave executable binaries at their default locations,
  409. skip this step.  Otherwise, you need to change path specifica-
  410. tions in your configuration directory.
  411.  
  412.    There are three paths used in the installation of Icon that
  413. are given by defined constants:
  414.  
  415.      RootPath   The root of the Icon hierarchy; used by scripts
  416.                 that build personalized interpreters and variant
  417.                 translators to locate Icon source code.
  418.  
  419.      IcontPath  The location of the Icon command-line processor,
  420.                 icont.
  421.  
  422.      IconxPath  The location of the Icon run-time executor,
  423.                 iconx.
  424.  
  425.    The default paths for most supported configurations are:
  426.  
  427.         #define RootPath   "/usr/icon/v8"
  428.         #define IcontPath  "/usr/icon/v8/bin/icont"
  429.         #define IconxPath  "/usr/icon/v8/bin/iconx"
  430.  
  431. They are slightly different for a few configurations that have
  432. non-standard naming conventions.
  433.  
  434.    The location of iconx is particularly important, since com-
  435. piled Icon programs do not stand alone but must find iconx to
  436. run.  To make this easy, the path specified in IconxPath is
  437. hardwired into compiled Icon programs. This means, however, that
  438. the value of IconxPath, which must be set before Icon is com-
  439. piled, is inherited by all subsequently compiled Icon programs.
  440. If iconx is moved to another place, the hardwired path is invali-
  441. dated.
  442.  
  443.    There are ways around this, however. If the environment vari-
  444. able ICONX is set, its value overrides the hardwired path. Furth-
  445. ermore, if ICONX is not set and iconx is not found on the
  446. hardwired path, the user's PATH environment variable is searched
  447. for iconx.  In fact, it is possible to configure Icon to disable
  448. the use of hardwired paths.  See Section 3 if you want to do
  449. this.  Nonetheless, it is advisable to chose an appropriate value
  450. for IconxPath.
  451.  
  452.    If you decide to change the default paths, you need to edit
  453. the file paths.h in the configuration directory for your system.
  454. The directory config/unix contains a subdirectory for each sup-
  455. ported system. For example, config/unix/sun3 contains the confi-
  456. guration information for the Sun-3 Workstation. To get to the
  457.  
  458.  
  459.  
  460.                              - 6 -
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. configuration information for your system,
  470.  
  471.         cd config/unix/name
  472.  
  473. where name is the name of your system.  For example, if you want
  474. the Icon hierarchy in /usr/irving/v8 and have the binaries in
  475. /usr/local/icon, edit paths.h to be
  476.  
  477.         #define RootPath  "/usr/irving/v8"
  478.         #define IcontPath "/usr/local/icon/icont"
  479.         #define IconxPath "/usr/local/icon/iconx"
  480.  
  481. Caution: If you are using a previous version of Icon and put
  482. iconx where the previous version was, all user programs will have
  483. to be recompiled, since iconx for Version 8 is incompatible with
  484. earlier versions of iconx.
  485.  
  486. Step_5:_Configuring_Icon_for_Your_System
  487.  
  488.    Configuring Icon creates a number of files for general use.
  489. Before starting the configuration, be sure your umask is set so
  490. that these files will be accessible.
  491.  
  492.    To configure Icon for your system, do
  493.  
  494.         make Configure name=name
  495.  
  496. where name is the name of your system as described above.  For
  497. example,
  498.  
  499.         make Configure name=vax_bsd
  500.  
  501. configures Version 8 of Icon for a VAX running BSD UNIX.
  502.  
  503. Step_6:_Checking_the_Size_of_a_Header_File
  504.  
  505.    Translating and linking an Icon program with icont produces an
  506. icode file, which can then be run. In order to make icode files
  507. executable, a bootstrap header, iconx.hdr, is provided. The size
  508. of iconx.hdr varies from system to system and is determined by
  509. the defined constant MaxHdr, which is given in a configuration
  510. file.  If value of MaxHdr is not large enough, the compilation of
  511. icont terminates with an error message. To be sure that MaxHdr is
  512. large enough for your system, do
  513.  
  514.         make Header
  515.  
  516. This compiles the header file and lists its size, followed by the
  517. value of MaxHdr. For example, on a VAX BSD system, typical output
  518. from this make is
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                              - 7 -
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.         cc -O -c ixhdr.c
  536.         cc -O -N ixhdr.o -o iconx.hdr
  537.         strip iconx.hdr
  538.         -rwxrwxr-x  1 icon         1912 Jan 10 18:32 iconx.hdr
  539.         #define MaxHdr  1950
  540.  
  541. The last two lines are what are important. In this example,
  542. MaxHdr is 1500 and the size of the header file is 1492 - that is,
  543. MaxHdr is large enough.
  544.  
  545.    If you find MaxHdr is not large enough for your system, edit
  546. config/unix/name/define.h and change the value of MaxHdr there to
  547. an appropriate value (where name is the name of your system as
  548. given above). It is advisable to leave a little spare room; some
  549. systems even require the value of MaxHdr to be rounded up. Don't
  550. worry about that at this point, but if icode files fail to exe-
  551. cute, come back to this step and increase MaxHdr.
  552.  
  553.    If you change MaxHdr, you must go back and start over with
  554. Step 5.
  555.  
  556. Step_7:_Compiling_Icon
  557.  
  558.    Next, compile Icon by
  559.  
  560.         make Icon
  561.  
  562. This takes a while. There may be warning messages on some sys-
  563. tems, but there should be no fatal errors.
  564.  
  565. Step_8:_Installing_Icon
  566.  
  567.    To install Icon, do
  568.  
  569.         make Install
  570.  
  571. Among other things, this copies icont and iconx to the locations
  572. specified in IcontPath and IconxPath, respectively.
  573.  
  574. Step_9:_Doing_Some_Simple_Tests
  575.  
  576.    For supported systems that compile and install without
  577. apparent difficulty, a few simple tests usually are sufficient to
  578. confirm that Icon is running properly. The following does the
  579. job:
  580.  
  581.         make Samples
  582.  
  583. This test compares local program output with the expected output.
  584. There should be no differences.  If there are none, you presum-
  585. ably have a running Version 8 Icon.
  586.  
  587.    Note: If Icon fails to run at all, this may be because there
  588. is not enough ``static'' space for it to start up. If this
  589.  
  590.  
  591.  
  592.                              - 8 -
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601. happens, check define.h in your configuration directory. If it
  602. contains a definition for MaxStatSize, try doubling it, and start
  603. over with Step 5. If define.h does not contain a definition for
  604. MaxStatSize, add one such as
  605.  
  606.         #define MaxStatSize 20480
  607.  
  608. and go back to Step 5. If this solves the problem, you may wish
  609. to reduce MaxStatSize to a smaller value that works in order to
  610. conserve memory. If this does not solve the problem, try increas-
  611. ing MaxStatSize even more (it is unlikely that much larger values
  612. will help).
  613.  
  614. Step_10:_Extensive_Testing
  615.  
  616.    If you want to runs more extensive tests, do
  617.  
  618.         make Test-all
  619.  
  620. This takes quite a while and does a lot of work. Some differences
  621. are to be expected, since tests include date, time, and local
  622. host information. There also may be insignificant differences in
  623. the format of floating-point numbers and the order of random
  624. numbers.  In addition to Test-all there are some individual tests
  625. of optional features.  See the main Makefile for more information
  626. about the tests.
  627.  
  628. 2.2__Icon_Program_Library
  629.  
  630.    The Icon program library contains a variety of programs and
  631. procedures.  This library not only is useful in its own right,
  632. but it provides numerous examples of programming techniques which
  633. may be helpful to novice Icon programmers. While this library is
  634. not necessary for running Icon programs, most sites install it.
  635.  
  636.    In addition to the library proper, the directory ipl/idol con-
  637. tains an object-oriented version of Icon written in Icon. Go to
  638. that directory for more information.
  639.  
  640. Step_1:_Building_the_Icon_Program_Library
  641.  
  642.    To build the Icon program library, do
  643.  
  644.         make Ipl
  645.  
  646. This puts compiled programs in ipl/icode and translated pro-
  647. cedures in ipl/ucode.
  648.  
  649. Step_2:_Testing_the_Icon_Program_Library
  650.  
  651.    To test the library, do
  652.  
  653.         make Test-ipl
  654.  
  655.  
  656.  
  657.  
  658.                              - 9 -
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667. No differences should show.
  668.  
  669. Step_3:_Installing_the_Icon_Program_Library
  670.  
  671.    You can copy the executable programs in ipl/icode and the
  672. translated procedures in ipl/ucode to public locations to make
  673. them more accessible, although they can be used from any location
  674. that is readable by the user.
  675.  
  676. 2.3__Personalized_Interpreters
  677.  
  678.    The personalized interpreter system allows an individual to
  679. build a private copy of Icon's run-time system, which then can be
  680. modified.
  681.  
  682.    Personalized interpreters are somewhat specialized and the
  683. typical Icon programmer has no need for them. However, if your
  684. site has a need for tailored versions of Icon, this system may be
  685. useful.
  686.  
  687. Step_1:_Building_the_Personalized_Interpreter_System
  688.  
  689.    To build the personalized interpreter system, do
  690.  
  691.         make PI
  692.  
  693.  
  694. Step_2:_Testing_the_Personalized_Interpreter_System
  695.  
  696.    For testing, do
  697.  
  698.         make Test-pi
  699.  
  700. There may be some warning messages during compilation, but there
  701. should be no fatal errors.
  702.  
  703. Step_3:_Installing_the_Personalized_Interpreter_System
  704.  
  705.    Personalized interpreter directories are constructed by the
  706. shell script icon_pi. You therefore may wish to place it in a
  707. public location:
  708.  
  709.         cp icon_pi location
  710.  
  711.  
  712. 2.4__Variant_Translators
  713.  
  714.    The variant translator system facilitates the construction of
  715. preprocessors for variants of the Icon programming language.
  716. This facility is even more specialized than the personalized
  717. interpreter system, but some forthcoming tools related to measur-
  718. ing the performance and behavior of Icon programs may use the
  719. variant translator system.
  720.  
  721.  
  722.  
  723.  
  724.                              - 10 -
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.    The variant translator system requires a version of yacc(1)
  734. with large regions. You may have to tailor your version of
  735. yacc(1) for this. See [5]. On systems with a limited amount of
  736. memory, this may not work at all. If there is a problem, it will
  737. show up during testing.
  738.  
  739.    There is no separate step for building the variant translator
  740. system.  However, Icon must be installed before testing the vari-
  741. ant translator system.
  742.  
  743. Step_1:_Testing_the_Variant_Translator_System
  744.  
  745.    For testing, do
  746.  
  747.         make Test-vt
  748.  
  749. There may be warning messages during compilation, but there
  750. should be no fatal errors.
  751.  
  752. Step_2:_Installing_the_Variant_Translator_System
  753.  
  754.    To put icon_vt, the shell script that builds variant transla-
  755. tor directories into a public place, do
  756.  
  757.         cp icon_vt location
  758.  
  759.  
  760. 2.5__Memory_Monitoring
  761.  
  762. Step_1:_Building_the_Monitoring_Programs
  763.  
  764.    To build the memory-monitoring programs, do
  765.  
  766.         make MemMon
  767.  
  768.  
  769. Step_2:_Testing_the_Memory-Monitoring_System
  770.  
  771.    For testing, do
  772.  
  773.         make Test-memmon
  774.  
  775. There will be differences in date lines and in some monitoring
  776. data because of different memory locations, but there should not
  777. be extensive differences.
  778.  
  779. 2.6__Benchmarking
  780.  
  781.    Test programs are provided for benchmarking Version 8 of Icon.
  782. To perform the benchmarks, go to the subdirectory bench and do
  783.  
  784.         make benchmark
  785.  
  786. See also the other material in that subdirectory.  It contains a
  787.  
  788.  
  789.  
  790.                              - 11 -
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799. form that you can use to record your benchmarks with the Icon
  800. Project (see Section 4).
  801.  
  802. 2.7__Finishing_Up
  803.  
  804. Step_1:_Installing_Documentation
  805.  
  806.    After Icon and any optional components have be installed, you
  807. may wish to install the appropriate manual pages in the standard
  808. location on your system. The manual pages are in the docs direc-
  809. tory:
  810.  
  811.         icont.1   manual page for Icon proper
  812.         icon_pi.1 manual page for the Icon personalized interpreter system
  813.         icon_vt.1 manual page for the Icon variant translator system
  814.         memmon.1  manual page for using the Icon memory-monitoring system
  815.         memmon.5  manual page for memory-monitoring data
  816.  
  817.  
  818.    The docs directory also contains machine-readable copiesHof
  819. technical reports related to Version 8 of Icon.
  820.  
  821. Step_2:_Cleaning_Up
  822.  
  823.    You can remove object files and test results by
  824.  
  825.         make Clean
  826.  
  827. You also can remove source files, but think twice about this,
  828. since source files may be useful to persons using personalized
  829. interpreters and variant translators.  In addition, you can
  830. remove files related to optional components of the Icon system
  831. that you do not need. If you are tight on space, you may wish to
  832. remove documents as well.
  833.  
  834.  
  835. 3.__Configuring_Version_8_for_a_New_UNIX_System
  836.  
  837.    Version 8 of Icon assumes that C ints are 16, 32, or 64 bits
  838. long.  If your system violates this assumption, don't try to go
  839. on - but check back with us, since we are may be able to provide
  840. some advice on how to proceed.
  841.  
  842.    There are 13 steps in installing Icon for a new system:
  843.  
  844.      1.*    Build a configuration directory.
  845.  
  846.      2.     Edit a configuration file to provide appropriate
  847.             definitions for your system.
  848.  
  849.      3.     Edit Makefile headers.
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.                              - 12 -
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.      4.*    Perform the installation as described in Section 2.
  866.  
  867.      5.*    Perform extensive testing.
  868.  
  869.      [6.]   Possibly provide assembly-language code for integer
  870.             overflow checking.
  871.  
  872.      [7.]   Implement and test co-expressions.
  873.  
  874.      [8.]   Install the personalized interpreter system.
  875.  
  876.      [9.]   Test the variant translator system.
  877.  
  878.      [10.]  Install and test the memory-monitoring system.
  879.  
  880.      [11.]  Run benchmarks.
  881.  
  882.      12.    Provide status information in your configuration
  883.             directory.
  884.  
  885.      13.    Send the contents of your configuration directory to
  886.             the Icon Project.
  887.  
  888. Step_1:_Building_a_New_Configuration_Directory
  889.  
  890.    First select a name for your system.  For compatibility with
  891. tools used at the Icon Project, the name should be in lowercase
  892. and consist of a mnemonic for the computer, which may be followed
  893. by an underscore and a mnemonic for the operating system, if
  894. there is more than one operating system for the computer.  Exam-
  895. ples are vax_bsd and vax_sysv.
  896.  
  897.    To build and initialize a new configuration directory,
  898.  
  899.         make System name=name
  900.  
  901. where name is the name of your system.
  902.  
  903.    As a result, the subdirectory name will contain the following
  904. files:
  905.  
  906.         define.h    main configuration file
  907.         paths.h     paths
  908.         icont.hdr   flags for the icont, common, and memmon Makefiles
  909.         iconx.hdr   flags and other definitions for the iconx Makefile
  910.         pi.hdr      flags for the personalized-interpreter Makefile
  911.         vt.hdr      flags for the variant-translator Makefile
  912.         rswitch.c   co-expression context switch
  913.         Ranlib      library randomizer for personalized interpreters
  914.  
  915.  
  916.    Alternatively, if there is a supported configuration for a
  917. system than is similar to yours, you may wish to copy the files
  918. from that configuration.
  919.  
  920.  
  921.  
  922.                              - 13 -
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.    To work on your configuration files,
  932.  
  933.         cd config/unix/name
  934.  
  935.  
  936. Step_2:_Editing_the_Main_Configuration_File,_define.h
  937.  
  938.    There are many defined constants in the source code for Icon
  939. that vary from system to system. Default values are provided for
  940. most of these so that the usual cases are handled automatically.
  941. The file define.h contains C preprocessor definitions for parame-
  942. ters that differ from the defaults or that must be provided on an
  943. individual basis. The initial contents of this file as produced
  944. in Step 1 above are for a ``vanilla'' system with the commonest
  945. values for parameters. If your system closely approximates a
  946. ``vanilla'' system, you will have few changes to make to
  947. define.h. Over the range of possible systems, there are many pos-
  948. sibilities as described below.
  949.  
  950.    The definitions are grouped into categories so that any neces-
  951. sary changes to define.h can be approached in a logical way.
  952.  
  953. ANSI Standard C: Icon preprocessor directives use string concate-
  954. nation and substitution of arguments within quotation marks. By
  955. default, the ``old-fashioned'', ad hoc method of accomplishing
  956. this in UNIX preprocessors is used.  A different method is speci-
  957. fied in the ANSI C draft standard [7].  The ANSI C draft standard
  958. also uses void * in place of the older char * for pointers to
  959. ``generic storage''.
  960.  
  961.    If your C compiler supports the ANSI C draft standard, add
  962.  
  963.         #define Standard
  964.  
  965. to define.h.
  966.  
  967.    Alternatively, you can define StandardPP or StandardC if your
  968. preprocessor is standard but your compiler isn't, or vice versa.
  969.  
  970. C sizing and alignment: There are four constants that relate to
  971. the size of C data and alignment:
  972.  
  973.         IntBits     (default: 32)
  974.         WordBits    (default: 32)
  975.         Double      (default: undefined)
  976.  
  977. IntBits is the number of bits in a C int. It may be 16, 32, or
  978. 64. WordBits is the number of bits in a C long (Icon's ``word'').
  979. It may be 32 or 64.  If your C library expects doubles to be
  980. aligned at double-word boundaries, add
  981.  
  982.         #define Double
  983.  
  984. to define.h.
  985.  
  986.  
  987.  
  988.                              - 14 -
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.    Most computers have downward-growing C stacks, for which stack
  998. addresses decrease as values are pushed. If you have an upward-
  999. growing stack, for which stack addresses increase as values are
  1000. pushed, add
  1001.  
  1002.         #define UpStack
  1003.  
  1004. to define.h.
  1005.  
  1006.    The alignment, in words, of stacks used by co-expressions is
  1007. controlled by
  1008.  
  1009.         StackAlign  (default: 2)
  1010.  
  1011. If your system needs a different alignment, provide an appropri-
  1012. ate definition in define.h.
  1013.  
  1014. Floating-point arithmetic: There are three optional definitions
  1015. related to floating-point arithmetic:
  1016.  
  1017.         Big         (default: 9007199254740092.)
  1018.         LogHuge     (default: 309)
  1019.         Precision   (default: 10)
  1020.  
  1021. The values of Big, LogHuge, and Precision give, respectively, the
  1022. largest floating-point number that does not lose precision, the
  1023. maximum base-10 exponent + 1 of a floating-point number, and the
  1024. number of digits provided in the string representation of a
  1025. floating-point number. If the default values given above do not
  1026. suit the floating-point arithmetic on your system, add appropri-
  1027. ate definitions to define.h.
  1028.  
  1029. Include file location: The location of the include file time.h
  1030. varies from system to system. Its default location is <time.h>.
  1031. If it resides at a different location on your system (such as
  1032. <sys/time.h>), add an appropriate definition of SysTime to
  1033. define.h, as in
  1034.  
  1035.         #define SysTime <sys/time.h>
  1036.  
  1037. If the location is incorrect, a fatal error will occur during the
  1038. compilation of src/common/time.c.
  1039.  
  1040.    The use of this definition also depends on your C preprocessor
  1041. making macro substitutions in #include directives. Most prepro-
  1042. cessors do, but if yours does not, edit src/common/time.c and
  1043. replace SysTime there by the appropriate value. If you have to do
  1044. this, make a note to come back later and place the definition
  1045. under the control of conditional compilation as described in Step
  1046. 4.
  1047.  
  1048. Run-time routines: The support for some run-time routines varies
  1049. from system to system.  The related constants are:
  1050.  
  1051.  
  1052.  
  1053.  
  1054.                              - 15 -
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.         IconGcvt    (default: undefined)
  1064.         IconQsort   (default: undefined)
  1065.         index       (default: undefined)
  1066.         rindex      (default: undefined)
  1067.  
  1068.  
  1069. If IconGcvt and IconQsort are defined, versions of gcvt(3) and
  1070. qsort(3) in the Icon system are used in place of the routines
  1071. normally provided in the C run-time system. These constants only
  1072. need to be defined if the versions of these routines in your
  1073. run-time system are defective or missing.
  1074.  
  1075.    Different versions of UNIX use different names for the rou-
  1076. tines for locating substrings within strings. The source code for
  1077. Icon uses index and rindex. The other possibilities are strchr
  1078. and strrchr. If your system uses the latter names, add
  1079.  
  1080.         #define index strchr
  1081.         #define rindex strrchr
  1082.  
  1083. to define.h.
  1084.  
  1085. Host identification: The identification of the host computer as
  1086. given by the Icon keyword &host needs to be specified in
  1087. define.h.  The definition
  1088.  
  1089.         #define HostStr "unknown host"
  1090.  
  1091. is provided in define.h initially.  This definition should be
  1092. changed to an appropriate value for your system.
  1093.  
  1094.    Alternatively, some systems provide direct mechanisms for
  1095. specifying the host in a standard way. In this case, remove the
  1096. definition of HostStr and provide an alternative as follows:
  1097.  
  1098.    On some versions of UNIX, notably Version 7 and 4.1bsd, the
  1099. file /usr/include/whoami.h contains the host name. If your system
  1100. has this file and you want to use this name, add
  1101.  
  1102.         #define WhoHost
  1103.  
  1104. to define.h.
  1105.  
  1106.    Some versions of UNIX, notably 4.2bsd and 4.3bsd, provide the
  1107. host name via the gethostname(2) system call. If your system sup-
  1108. ports this system call and you want to use this name, add
  1109.  
  1110.         #define GetHost
  1111.  
  1112. to define.h.
  1113.  
  1114.    Some versions of UNIX, such as System V, provide the host name
  1115. via the uname(2) system call. If your system supports this call
  1116. and you want to use this name, add
  1117.  
  1118.  
  1119.  
  1120.                              - 16 -
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.         #define UtsName
  1130.  
  1131. to define.h.
  1132.  
  1133.    Note: Only one of these methods of specifying the host name
  1134. can be used.
  1135.  
  1136. Hardwired paths: As mentioned in Section 2.1, a hardwired path
  1137. normally is used for finding iconx. This feature can be removed
  1138. by adding
  1139.  
  1140.         #define NoFixedPaths
  1141.  
  1142. to define.h.
  1143.  
  1144. Storage management: Icon includes its own versions of malloc(3),
  1145. calloc(3), realloc(3), and free(3) so that it can manage its
  1146. storage region without interference from allocation by the
  1147. operating system. Normally, Icon's versions of these routines are
  1148. loaded instead of the system library routines.
  1149.  
  1150.    Leave things are they are in the initial configuration, but if
  1151. your system insists on loading its own library routines, multiple
  1152. definitions will occur as a result of the ld in src/iconx.  If
  1153. multiple definitions occur, go back and add
  1154.  
  1155.         #define IconAlloc
  1156.  
  1157. to define.h. This definition causes Icon's routines to be named
  1158. differently to avoid collision with the system routine names.
  1159.  
  1160.    One possible effect of this definition is to interfere with
  1161. Icon's expansion of its memory region in case the initial values
  1162. for allocated storage are not large enough to accommodate a pro-
  1163. gram that produces a lot of data.  This problem appears in the
  1164. form of run-time errors 305-307. Users can get around this prob-
  1165. lem on a case-by-case basis by increasing the initial values for
  1166. allocated storage by setting environment variables [8].
  1167.  
  1168.    Icon's dynamic storage allocation system uses three contiguous
  1169. memory regions that it expands if necessary. This method relies
  1170. on the use of brk(2) and sbrk(2) and the system treatment of user
  1171. memory space as one logically contiguous region. This may not
  1172. work on some systems that treat memory as segmented or do not
  1173. support brk() and sbrk(). On such systems, it may be necessary to
  1174. add
  1175.  
  1176.         #define FixedRegions
  1177.  
  1178. to define.h.  The effect of this definition is to assign fixed-
  1179. sized regions for Icon's use. These regions may not be shared or
  1180. expanded and all of available memory may not be used. This option
  1181. should be used only if necessary.
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                              - 17 -
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195. The bootstrap header: As described In Section 2.1, Step 6, a
  1196. bootstrap header is used to make icode files executable.  The
  1197. space reserved for the header is determined by
  1198.  
  1199.         #define MaxHdr  (default: 4096)
  1200.  
  1201.  
  1202.    On some systems, many routines may be included in the header
  1203. even if they are not needed.  Start by assuming this is not a
  1204. problem, but if MaxHeader has to be made impractically large, you
  1205. can eliminate the header by adding
  1206.  
  1207.         #define NoHeader
  1208.  
  1209. to define.h.  Note: If NoHeader is defined, the value of MaxHdr
  1210. is irrelevant.
  1211.  
  1212.    The effect of this definition is to render Icon programs non-
  1213. executable. Instead, they must be run by using the -x option
  1214. after the program name when icont is used, as in
  1215.  
  1216.         icont prog.icn -x
  1217.  
  1218. Such a program also can be run as an argument of iconx, as in
  1219.  
  1220.         iconx prog
  1221.  
  1222. where prog is the result of translating and linking prog.icn as
  1223. in the previous example.
  1224.  
  1225. Storage regions: The sizes of Icon's run-time storage regions for
  1226. allocated blocks and strings normally are the same for all imple-
  1227. mentations. However, different values can be set:
  1228.  
  1229.         MaxStatSize (default: 20480 if co-expressions are enabled, else 1024)
  1230.         MaxAbrSize  (default: 65000)
  1231.         MaxStrSize  (default: 65000)
  1232.  
  1233. Since users can override the set values with environment vari-
  1234. ables, it is unwise to change them from their defaults except in
  1235. unusual cases.
  1236.  
  1237.    The sizes for Icon's main interpreter stack and co-expression
  1238. stacks also can be set:
  1239.  
  1240.         MStackSize  (default: 10000)
  1241.         StackSize   (default: 2000)
  1242.  
  1243. As for the block and string storage regions, it is unwise to
  1244. change the default values except in unusual cases.
  1245.  
  1246.    Finally, with fixed-regions storage management, a list used
  1247. for pointers to strings during garbage collection, can be sized:
  1248.  
  1249.  
  1250.  
  1251.  
  1252.                              - 18 -
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.         QualLstSize (default: 5000)
  1262.  
  1263. Like the sizes above, this one normally is best left unchanged.
  1264.  
  1265.  
  1266. Dynamic hashing:
  1267.  
  1268.    Four parameters configure the implementation of tables and
  1269. sets:
  1270.  
  1271.         HSlots      Initial number of hash buckets; it must be a
  1272.                     power of 2
  1273.  
  1274.         HSegs       Maximum number of hash bucket segments
  1275.  
  1276.         MaxHLoad    Maximum allowable loading factor
  1277.  
  1278.         MinHLoad    Minimum loading factor for new structures
  1279.  
  1280.    The default values (listed below) are appropriate for most
  1281. systems. If you want to change the values, read the discussion
  1282. that follows.
  1283.  
  1284.    Every set or table starts with HSlots hash buckets, using one
  1285. bucket segment.  When the average hash bucket exceeds MaxHLoad
  1286. entries, the number of buckets is doubled and one more segment is
  1287. consumed.  This repeats until HSegs segments are in use; after
  1288. that, structure still grows but no more hash buckets are added.
  1289.  
  1290.    MinHLoad is used only when copying a set or table or when
  1291. creating a new set through the intersection, union, or difference
  1292. of two other sets.  In these cases a new set may be more lightly
  1293. loaded than otherwise, but never less than MinHLoad if it exceeds
  1294. a single bucket segment.
  1295.  
  1296.    For all machines, the default load factors are 5 for MaxHLoad
  1297. and 1 for MinHLoad.  Because splitting or combining buckets
  1298. halves or doubles the load factor, MinHLoad should be no more
  1299. than half MaxHLoad.  The average number of elements in a hash
  1300. bucket over the life of a structure is about 2/3xMaxHLoad, assum-
  1301. ing the structure is not so huge as to be limited by HSegs.
  1302. Increasing MaxHLoad delays the creation of new hash buckets,
  1303. reducing memory demands at the expense of increased search times.
  1304. It has no effect on the memory requirements of minimally-sized
  1305. structures.
  1306.  
  1307.    HSlots and HSegs interact to determine the minimum size of a
  1308. structure and its maximum efficient capacity.  The size of an
  1309. empty set or table is directly related to HSegs+HSlots; smaller
  1310. values of these parameters reduce the memory needs of programs
  1311. using many small structures.  Doubling HSlots delays the onset of
  1312. the first structure reorganization until twice as many elements
  1313. have been inserted.  It also doubles the capacity of a structure,
  1314. as does increasing HSegs by 1.
  1315.  
  1316.  
  1317.  
  1318.                              - 19 -
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.    The maximum number of hash buckets is HSlotsx(2^(HSegs-1)).  A
  1328. structure can be considered ``full'' when it contains MaxHLoad
  1329. times that many entries; beyond that, lookup times gradually
  1330. increase as more elements are added.  Until a structure becomes
  1331. full, the values of HSlots and HSegs do not affect lookup times.
  1332.  
  1333.    For machines with 16-bit ints, the defaults are 4 for HSlots
  1334. and 6 for HSegs.  Sets and tables grow from 4 hash buckets to a
  1335. maximum of 128, and become full at 640 elements.  For other
  1336. machines, the defaults are 8 for HSlots and 10 for HSegs.  Sets
  1337. and tables grow from 8 hash buckets to a maximum of 4096, and
  1338. become full at 20480 elements.
  1339.  
  1340. Memory monitoring: The number of bytes for reporting block sizes
  1341. in allocation history files produced by memory monitoring [6] is
  1342. determined by
  1343.  
  1344.         MMUnits     (default: WordSize)
  1345.  
  1346. A smaller value may be needed if the size of any block in Icon's
  1347. allocated block region is not an even multiple of WordSize. This
  1348. occurs, for example, on computers with 80-bit (1-1/2 word)
  1349. floating-point numbers, in which case the value of MMUnits should
  1350. be defined to be 2.
  1351.  
  1352. Clock Rate: Hz defines the units returned by the times() function
  1353. call.  Check the man page for this function on your system. If it
  1354. says that times are returned in terms of 1/60 second, no action
  1355. is needed. Otherwise, define Hz in define.h to be the number of
  1356. times() units in one second.
  1357.  
  1358.    The man page may refer you to an additional file such as
  1359. /usr/include/sys/param.h. If so, check the value there, and
  1360. define Hz accordingly.
  1361.  
  1362. Executable Images: If you have a BSD UNIX system and want to
  1363. enable the function save(s), which allows an executable image of
  1364. a running Icon program to be saved [9], add
  1365.  
  1366.         #define ExecImages
  1367.  
  1368. to define.h.
  1369.  
  1370. External functions and calling Icon from C: Version 8 of Icon
  1371. provides a mechanism for calling C functions from Icon programs
  1372. [10]. Such functions are called external functions.  The mechan-
  1373. ism for calling C functions from Icon normally is enabled.  It
  1374. can be disabled by adding
  1375.  
  1376.         #define NoExternalFunctions
  1377.  
  1378. to define.h.
  1379.  
  1380.    It also is possible to call an Icon program from C [10].  This
  1381.  
  1382.  
  1383.  
  1384.                              - 20 -
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393. feature normally is disabled.  It can be enabled by adding
  1394.  
  1395.         #define IconCalling
  1396.  
  1397. to define.h.
  1398.  
  1399.    The ability to call an Icon program from C is incompatible
  1400. with executable images. If ExecImages is defined, IconCalling has
  1401. no effect.
  1402.  
  1403. Large integers: Version 8 of Icon supports arithmetic on integers
  1404. of arbitrarily large magnitude. This features increases the size
  1405. of iconx by 15-20%. It may be disabled by adding
  1406.  
  1407.         #define NoLargeInts
  1408.  
  1409. to define.h.
  1410.  
  1411. Co-expressions: The implementation of co-expressions requires an
  1412. assembly-language routine.  Initially, define.h contains
  1413.  
  1414.         #define NoCoexpr
  1415.  
  1416. This definition disables co-expressions.  Leave this definition
  1417. in for the first round, although you may want to remove it later
  1418. and implement these features (see Step 7).
  1419.  
  1420. Step_3:_Makefile Headers
  1421.  
  1422.    The file icont.hdr provides headers for Makefiles in the
  1423. source directories src/common, src/icont and src/memmon.  The
  1424. file iconx.hdr provides a header for the Makefile in src/iconx.
  1425. These headers are prepended to the standard bodies for the
  1426. Makefiles during configuration.
  1427.  
  1428.    These headers serve to specify flags for cc(1) and ld(1) via
  1429. CFLAGS, LDFLAGS, and LIBS.  If your C optimizer is robust, you
  1430. may wish to start with
  1431.  
  1432.         CFLAGS= -O
  1433.  
  1434. in all these headers.  If you encounter problems during testing,
  1435. suspect your optimizer first and try compiling Icon without the
  1436. -O flag.
  1437.  
  1438.    Other cc and ld flags vary considerably from system to system.
  1439. You may want to review your local manual pages for these proces-
  1440. sors and look at the header files in the other configuration
  1441. areas.
  1442.  
  1443.    LIBS is provided in case you need to load system routines
  1444. after everything else in the ld step.
  1445.  
  1446.    There another definition in iconx.hdr, RSWITCH, which depends
  1447.  
  1448.  
  1449.  
  1450.                              - 21 -
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459. on whether the local co-expression context switch is written in C
  1460. or assembly language. The initial value of this definition is
  1461. rswitch.c and a dummy C routine is provided. To start out, leave
  1462. this definition as it is; the default routine can be replaced
  1463. later. See Step 7.
  1464.  
  1465.    The file pi.hdr provides a header for the personalized inter-
  1466. preter Makefile (which is named Pimakefile). In addition to the
  1467. usual cc and ld flags, you should provide definitions for XCFLAGS
  1468. and XLDFLAGS that are the same as those for CFLAGS and LDFLAGS in
  1469. icont.hdr. This assures that the header file in the personalized
  1470. interpreter is the same size as the one in the regular version of
  1471. Icon.
  1472.  
  1473.    The file vt.hdr provides a header for the variant translator
  1474. Makefile (which is named Vtmake2). It should have the same cc and
  1475. ld flags as icont.hdr.
  1476.  
  1477. Step_4:_Installation
  1478.  
  1479.    Once you have edited the files as described in the previous
  1480. steps, proceed with the installation as described in Steps 5
  1481. through 9 at the beginning of Section 2.  You may need to iterate
  1482. if problems show up.  If you make a change in a configuration
  1483. file after a compilation, be sure to perform the configuration
  1484. step again; some aspects of the configuration are far-reaching
  1485. and not obvious.
  1486.  
  1487.    Note: The configuration system is designed to avoid the need
  1488. for modifications to the distributed source code for Version 8.
  1489. However, you may run into problems that require modifications to
  1490. the source code itself.  If you need to modify the source code,
  1491. do it under the control of conditional compilation keyed to the
  1492. name of your system. Add
  1493.  
  1494.         #define NAME
  1495.  
  1496. to define.h, where NAME is an all-uppercase name that identifies
  1497. your system.  For example, the define.h for Sun Workstations con-
  1498. tains
  1499.  
  1500.         #define SUN
  1501.  
  1502.  
  1503. Then use
  1504.  
  1505.         #ifdef NAME
  1506.              .
  1507.              .
  1508.              .
  1509.         #endif                   /* NAME */
  1510.  
  1511. or similar constructions where you need local source-code modifi-
  1512. cations.  For example, this technique can be used to handle the
  1513.  
  1514.  
  1515.  
  1516.                              - 22 -
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525. problem that may arise with SysTime, described in Step 2. Note
  1526. that nested #ifdefs may be needed in places where there are
  1527. several different local modifications.
  1528.  
  1529.    It is important to be consistent and careful about the use of
  1530. such conditional compilations; if done properly, your modifica-
  1531. tions can be backed into the master version of the source code at
  1532. the Icon Project and will be in place for you when subsequent
  1533. versions are released.  See Step 11.
  1534.  
  1535.    If you need to add C functions to your implementation, put
  1536. them in tlocal.c for icont and in rlocal.c for iconx.
  1537.  
  1538. Step_5:_Testing
  1539.  
  1540.    More testing is recommended for a new installation than for
  1541. one that has been successfully installed elsewhere. You should do
  1542. Step 10 at the beginning of Section 2:
  1543.  
  1544.         make Test-all
  1545.  
  1546.  
  1547. Step_6:_Overflow_Checking
  1548.  
  1549.    The code to check integer overflow in iconx is written in C.
  1550. Some improvement in performance may be obtained by replacing this
  1551. C code by assembly-language code. This is entirely optional. If
  1552. you want to do it, add
  1553.  
  1554.         #define AsmOver
  1555.  
  1556. to define.h and provide assembly-language routines add(), sub(),
  1557. mul(), and neg() using the corresponding C routines at the end of
  1558. rmisc.c as examples.
  1559.  
  1560.    If your C compiler supports the asm directive, place your code
  1561. in rlocal.c in the UNIX section under control of an appropriate
  1562. defined symbol that identifies your system.  If you need to
  1563. define such a symbol, place the definition is define.h.
  1564.  
  1565. Step_7:_Co-Expressions
  1566.  
  1567.    Once Icon is working properly, you may wish to implement co-
  1568. expressions.  Note: If your system does not allow the C stack to
  1569. be at an arbitrary place in memory, there is probably little hope
  1570. of implementing co-expressions.  If you do not implement co-
  1571. expressions, the only effect will be that Icon programs that
  1572. attempt to use co-expressions will terminate with an error mes-
  1573. sage.
  1574.  
  1575.    All aspects of co-expression creation and activation are writ-
  1576. ten in C in Version 8 except for a routine, coswitch, that is
  1577. needed for context switching. This routine requires assembly
  1578. language, since it must manipulate hardware registers.  It either
  1579.  
  1580.  
  1581.  
  1582.                              - 23 -
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591. can be written as a C routine with asm directives or as an assem-
  1592. bly language routine.
  1593.  
  1594.    When a new configuration directory is set up, a file rswitch.c
  1595. is provided with a version of coswitch that results in error ter-
  1596. mination if an Icon program attempts to activate a co-expression.
  1597. If you implement coswitch in C, modify rswitch.c.  Alternatively,
  1598. if you implement coswitch in assembly language, place it in a new
  1599. file, rswitch.s.
  1600.  
  1601.    Calls to the context switch have the form
  1602. coswitch(old_cs,new_cs,first), where old_cs is a pointer to an
  1603. array of words that contain C state information for the current
  1604. co-expression, new_cs is a pointer to an array of words that hold
  1605. C state information for a co-expression to be activated, and
  1606. first is 1 or 0, depending on whether or not the new co-
  1607. expression has or has not been activated before.  The zeroth ele-
  1608. ment of a C state array always contains the hardware stack
  1609. pointer (sp) for that co-expression. The other elements can be
  1610. used to save any C frame pointers and any other registers your C
  1611. compiler expects to be preserved across calls.
  1612.  
  1613.    The default size of the array for the C state is 15. This
  1614. number may be changed by adding
  1615.  
  1616.         #define CStateSize n
  1617.  
  1618. to define.h, where n is the number of elements needed.
  1619.  
  1620.    The first thing coswitch does is to save the current pointers
  1621. and registers in the old_cs array. Then it tests first.  If first
  1622. is zero, coswitch sets sp from new_cs[0], clears the C frame
  1623. pointers, and calls interp. If first is not zero, it loads the
  1624. (previously saved) sp, C frame pointers, and registers from
  1625. new_cs and returns.
  1626.  
  1627.    Written in C, coswitch has the form:
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.                              - 24 -
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.         /*
  1658.          * coswitch
  1659.          */
  1660.         coswitch(old_cs, new_cs, first)
  1661.         long *old_cs, *new_cs;
  1662.         int first;
  1663.         {
  1664.                             .
  1665.                             .
  1666.                             .
  1667.                     /* save sp, frame pointers, and other registers in old_cs */
  1668.                             .
  1669.                             .
  1670.                             .
  1671.            if (first == 0) {          /* this is first activation */
  1672.                             .
  1673.                             .
  1674.                             .
  1675.                     /* load sp from new_cs[0] and clear frame pointers */
  1676.                             .
  1677.                             .
  1678.                             .
  1679.               interp(0, 0);
  1680.               syserr("interp() returned in coswitch");
  1681.               }
  1682.  
  1683.  
  1684.            else {
  1685.                             .
  1686.                             .
  1687.                             .
  1688.                     /* load sp, frame pointers, and other registers from new_cs */
  1689.                             .
  1690.                             .
  1691.                             .
  1692.               }
  1693.         }
  1694.  
  1695. Appendix B contains a listing of coswitch for a VAX running BSD.
  1696. Other examples are contained in the configuration directories in
  1697. config/unix.
  1698.  
  1699.    After you implement coswitch, remove the #define NoCoexpr from
  1700. define.h and replace rswitch.c or rswitch.s in your configuration
  1701. directory as described above.  The configuration process will
  1702. copy your file to the appropriate place prior to compilation. If
  1703. you use rswitch.s, change the definition of RSWITCH in iconx.hdr
  1704. to
  1705.  
  1706.         RSWITCH=rswitch.s
  1707.  
  1708. If your assembler requires special flags, add an appropriate
  1709. definition for OFLAGS to iconx.hdr.
  1710.  
  1711.  
  1712.  
  1713.  
  1714.                              - 25 -
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.    To test your context switch,
  1724.  
  1725.         make Test-coexpr
  1726.  
  1727. Ideally, there should be no differences in the comparison of out-
  1728. puts.
  1729.  
  1730.    If you have trouble with your context switch, the first thing
  1731. to do is double-check the registers that your C compiler expects
  1732. to be preserved across calls - different C compilers on the same
  1733. computer may have different requirements.
  1734.  
  1735.    Another possible source of problems is built-in stack check-
  1736. ing.  Co-expressions rely on being able to specify an arbitrary
  1737. region of memory for the C stack. If your C compiler generates
  1738. code for stack probes that expects the C stack to be at a
  1739. specific location, you may need to disable this code (via a C
  1740. compiler option) or replace it with something more appropriate.
  1741.  
  1742. Step_8:_Personalized_Interpreters
  1743.  
  1744.    The personalized interpreter system uses ar(1). On most UNIX
  1745. systems, it is necessary to use ranlib(1) so that the loader can
  1746. access the archive. The script Ranlib that is provided when a new
  1747. configuration directory is initialized contains calls of ranlib
  1748. for this purpose.
  1749.  
  1750.    Some UNIX systems, notably System V, handle this problem
  1751. directly in ar(1) and do not have ranlib(1). If your system does
  1752. not use ranlib(1), change Ranlib to an empty script by
  1753.  
  1754.         echo "" >Ranlib
  1755.  
  1756. in your configuration directory.
  1757.  
  1758.    Test your personalized interpreter system as described in Sec-
  1759. tion 2.3.
  1760.  
  1761. Step_9:_Variant_Translators
  1762.  
  1763.    Normally no work is needed for variant translators on a newly
  1764. configured system.  Test them as described in Section 2.4.
  1765.  
  1766. Step_10:_Memory_Monitoring
  1767.  
  1768.    Normally no work is needed for memory monitoring on a newly
  1769. configured system.  Test it as described in Section 2.5.
  1770.  
  1771. Step_11:_Benchmarking
  1772.  
  1773.    Run the benchmarks as described in Section 2.6.
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.                              - 26 -
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789. Step_12:_Status_Information
  1790.  
  1791.    Each configuration directory contains a file named status that
  1792. describes the state of the configuration. A placeholder is pro-
  1793. vided when a new configuration directory is set up.  When your
  1794. configuration is complete, edit status appropriately, using a
  1795. status file in another configuration directory as a model.
  1796.  
  1797. Step_13:_Sending_Your_Configuration_Information_to_the_Icon_Project
  1798.  
  1799.    When your newly installed system is complete, send a copy of
  1800. any files you modified (both in your configuration directory and
  1801. in the source code, if changes there were necessary) to the Icon
  1802. Project as given in Section 4.
  1803.  
  1804.    Your changes will be added to the master Icon system and will
  1805. be available in future releases of Icon.
  1806.  
  1807.    Files can be sent on any convenient medium, such as MS-DOS
  1808. diskettes or magnetic tape in tar or cpio format. Electronic mail
  1809. also can be used.
  1810.  
  1811.  
  1812. 4.__Communicating_with_the_Icon_Project
  1813.  
  1814.    If you run into problems with the installation of Version 8 of
  1815. Icon, contact the Icon Project:
  1816.  
  1817.         Icon Project
  1818.         Department of Computer Science
  1819.         Gould-Simpson Building
  1820.         The University of Arizona
  1821.         Tucson, AZ   85721
  1822.         U.S.A.
  1823.         (602) 621-4049
  1824.         icon-project@cs.arizona.edu     (Internet)
  1825.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  1826.  
  1827.  
  1828.    Please also let us know if you have any suggestions for
  1829. improvements to the installation process or corrections or
  1830. refinements to configuration files for supported systems.
  1831.  
  1832. References
  1833.  
  1834.  
  1835. 1.   R. E. Griswold, Installation Guide for Version 8 of Icon on
  1836.      UNIX Systems, The Univ. of Arizona Tech. Rep. 90-2, 1990.
  1837.  
  1838. 2.   R. E. Griswold, Transporting Version 8 of Icon, The Univ. of
  1839.      Arizona Tech. Rep. 90-5, 1990.
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.                              - 27 -
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855. 3.   R. E. Griswold, The Icon Program Library, The Univ. of
  1856.      Arizona Tech. Rep. 90-7, 1990.
  1857.  
  1858. 4.   R. E. Griswold, Personalized Interpreters for Version 8 of
  1859.      Icon, The Univ. of Arizona Tech. Rep. 90-3, 1990.
  1860.  
  1861. 5.   R. E. Griswold and K. Walker, Variant Translators for
  1862.      Version 8 of Icon, The Univ. of Arizona Tech. Rep. 90-4,
  1863.      1990.
  1864.  
  1865. 6.   G. M. Townsend, The Icon Memory Monitoring System, The Univ.
  1866.      of Arizona Icon Project Document IPD113, 1990.
  1867.  
  1868. 7.   Technical Committee X3J11, Draft Proposed American National
  1869.      Standard for Information Systems -  Programming Language C,
  1870.      1988.
  1871.  
  1872. 8.   R. E. Griswold, ICONT(1), manual page for UNIX Programmer's
  1873.      Manual, The Univ. of Arizona Icon Project Document IPD109,
  1874.      1990.
  1875.  
  1876. 9.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  1877.      Tech. Rep. 90-1, 1990.
  1878.  
  1879. 10.  R. E. Griswold, Icon-C Calling Interfaces, The Univ. of
  1880.      Arizona Tech. Rep. 90-8, 1990.
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.                              - 28 -
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.                 Appendix A - Supported Configurations
  1922.  
  1923.  
  1924.  
  1925.    Asterisks make ``supported'' configurations that have been
  1926. tested under Version 7.5 or 8.
  1927.  
  1928.      computer              UNIX system      name
  1929.      Amdahl                UTS              amdahl_uts
  1930.      Apollo Workstation*   BSD              domain_bsd
  1931.      Astronautics ZS-1     UNIX             zs1
  1932.      AT&T 3B1 (UNIX PC)    System III       unixpc
  1933.      AT&T 3B2              System V         att3b_2
  1934.      AT&T 3B5              System V         att3b_5
  1935.      AT&T 3B15             System V         att3b_15
  1936.      AT&T 3B20             System V         att3b_20
  1937.      AT&T 3B4000           System V         att3b_4000
  1938.      AT&T 6386             System V         att6386
  1939.      CDC Cyber             NOS/VE           cdc_vxve
  1940.      Celerity              4.2BSD           celerity_bsd
  1941.      Codata 3400           Unisis           codata
  1942.      Convergent MegaFrame  CTIX             mega
  1943.      Convex C-1/2          BSD              convex_bsd
  1944.      Cray-2                UNICOS           Cray-2
  1945.      DecStation 3100*      Ultrix           dec_3100
  1946.      DG AViiON*            System V         aviion
  1947.      DIAB                  D-NIX            diab_dnix
  1948.      Elxsi-6400*           BSD              elxsi_bsd
  1949.      Encore                UMAX             multimax_bsd
  1950.      Gould Powernode       UTX              gould_pn
  1951.      HP 9000/330*          HP-UX            hp9000_s300
  1952.      HP 9000/500           HP-UX            hp9000_s500
  1953.      HP 9000/800           HP-US            hp9000_s800
  1954.      IBM PS/2              AIX              ps2_aix
  1955.      IBM RT Workstation    ACIS             rtpc_acis
  1956.      IBM RT Workstation    AIX              rtpc_aix
  1957.      Intel 286*            XENIX 286        i286_xenix
  1958.      Intel 386*            System V         i386_sysv
  1959.      Intel 386*            XENIX 386        i386_xenix
  1960.      Iris 4D/20*           BSD              iris4d
  1961.      Intergraph Clipper    System V         clix
  1962.      Masscomp 5500         System V         masscomp
  1963.      Microport V/AT        System V         microport
  1964.      MIPS/r3000*           System V         mips
  1965.      Motorola 8000/400     System V         mot_8000
  1966.      Multifow Trace        UNIX             trace
  1967.      NeXT*                 Mach             next
  1968.      Plexus P60            System V         plexus
  1969.      Pyramid 90x           4.2BSD           pyramid_bsd
  1970.      Ridge 32              ROS              ridge
  1971.      Sequent Balance 8000  Dynix            balance_dynix2
  1972.      Sequent Symmetry*     Dynix            symmetry
  1973.      Siemens MX500         SINIX            mx_sinix
  1974.      Sun 2 Workstation     SunOS            sun2
  1975.  
  1976.  
  1977.  
  1978.                              - 29 -
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.      Sun 3 Workstation*    SunOS            sun3
  1988.      Sun 3 with 68881      SunOS            sun3_68881
  1989.      Sun 386i              SunOS            sun386i
  1990.      Sun 4 Workstation*    SunOS            sun4
  1991.      Unisys 7000/40        4.3BSD           tahoe_bsd
  1992.      VAX-11                4.1BSD           vax_41_bsd
  1993.      VAX-11*               4.2BSD and 4.3BSDvax_bsd
  1994.      VAX-11                System V         vax_sysv
  1995.      VAX-11                Ultrix           vax_ultrix
  1996.      VAX-11                9th Edition      vax_v9
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.                              - 30 -
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.        Appendix B - A Sample Co-Expression Context Switch
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.    The co-expression context switch for a VAX running BSD is:
  2061.  
  2062.  
  2063.         coswitch(old_cs, new_cs, first)
  2064.         int *old_cs, *new_cs;
  2065.         int first;
  2066.  
  2067.  
  2068.         {
  2069.            asm("  movl 4(ap),r0");
  2070.            asm("  movl 8(ap),r1");
  2071.            asm("  movl sp,0(r0)");
  2072.            asm("  movl fp,4(r0)");
  2073.            asm("  movl ap,8(r0)");
  2074.            asm("  movl r11,16(r0)");
  2075.            asm("  movl r10,20(r0)");
  2076.            asm("  movl r9,24(r0)");
  2077.            asm("  movl r8,28(r0)");
  2078.            asm("  movl r7,32(r0)");
  2079.            asm("  movl r6,36(r0)");
  2080.  
  2081.  
  2082.            if (first == 0) {    /* this is first activation */
  2083.               asm("  movl 0(r1),sp");
  2084.               asm("  clrl fp");
  2085.               asm("  clrl ap");
  2086.               interp(0, 0);
  2087.               syserr("interp() returned in coswitch");
  2088.               }
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.                              - 31 -
  2111.  
  2112.  
  2113.